%a{:name => 'overview'}
#documentation
  .route-section
    .route-info
      %h1 easyBacklog API documentation

      %p
        The easyBacklog API is organized around #{link_to 'REST', 'http://en.wikipedia.org/wiki/Representational_State_Transfer'}.
        Our API is designed to have predictable, resource-oriented URLs, to use #{link_to 'HTTP response codes', 'http://en.wikipedia.org/wiki/List_of_HTTP_status_codes'}
        to indicate API errors, and to use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients.
        #{link_to 'JSON', 'http://www.json.org/'} or #{link_to 'XML', 'http://en.wikipedia.org/wiki/XML'} will be returned in all responses from the API, including errors.

      %p
        Please note that all dates and times are returned using #{link_to 'ISO 8601 format', 'http://en.wikipedia.org/wiki/ISO_8601'}, and we recommend that you send all date and or time arguments in this format as well.

      %p
        All EXAMPLE REQUESTS listed on the right can be run directly from your console.  Copy and paste the curl commands into your terminal to test the API using our demo API account.  Please note however that the demo API account only has read rights so no updates will succeed.

      %p
        We monitor our API constantly to ensure we hit our target of at least 99.99% uptime.  In addition, we openly publicise our API uptime using a 3rd party service, #{link_to 'click here to view the current API service status and uptime reports', 'http://api-status.easybacklog.com/lfg0irj2b7v7/573193'}.

    .route-example.first-route-list
      %h2 API Endpoint
      %code= api_end_point

      %h2 Summary of Resource URL Patterns
      %code
        %ul
          %li.heading CRUD (read and write)
          %li= link_to raw("/#{content_tag(:b, 'accounts')}"), '#accounts'
          %li= link_to raw("/#{content_tag(:b, 'companies')}"), '#companies'
          %li= link_to raw("/accounts/{ACCOUNT_ID}/#{content_tag(:b, 'backlogs')}"), '#backlogs'
          %li= link_to raw("/accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}/#{content_tag(:b, 'snapshots')}"), '#snapshots'
          %li= link_to raw("/backlogs/{BACKLOG_ID}/#{content_tag(:b, 'themes')}"), '#themes'
          %li= link_to raw("/backlogs/{BACKLOG_ID}/#{content_tag(:b, 'sprints')}"), '#sprints'
          %li= link_to raw("/themes/{THEME_ID}/#{content_tag(:b, 'stories')}"), '#stories'
          %li= link_to raw("/stories/{STORY_ID}/#{content_tag(:b, 'acceptance-criteria')}"), '#acceptance-criteria'
          %li= link_to raw("/sprints/{SPRINT_ID}/#{content_tag(:b, 'sprint-stories')}"), '#sprint-stories'
          %li.heading Read only (lists)
          %li= link_to raw("/#{content_tag(:b, 'locales')}"), '#locales'
          %li= link_to raw("/#{content_tag(:b, 'scoring-rules')}"), '#scoring-rules'
          %li= link_to raw("/#{content_tag(:b, 'sprint-story-statuses')}"), '#sprint-story-statuses'
    %a{:name => 'authentication'}

  .route-section
    .route-info
      %h2 Authentication

      %p
        You authenticate to the easyBacklog API by providing one of your #{link_to 'API keys', 'https://easybacklog.com/user-tokens'} in the request.
        You can #{link_to 'manage your API keys', 'https://easybacklog.com/user-tokens'} from your #{link_to 'account', 'https://easybacklog.com/users/edit'}. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!
        All API requests must be made over #{link_to 'HTTPS', 'http://en.wikipedia.org/wiki/HTTP_Secure'}. Calls made over plain HTTP will fail. You must authenticate for all requests.

      %p
        Authentication to the API occurs via one of the following:

  .route-section.list-start
    .route-info.indent
      %h3= link_to 'HTTP Basic Auth', 'http://en.wikipedia.org/wiki/Basic_access_authentication'
      Provide your user ID as the basic auth username, and your API key as the basic auth password.  You can find your user ID at the bottom of your #{link_to 'API access page', 'https://easybacklog.com/user-tokens'}.
    .route-example
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts \
             -u #{demo_api_user_id}:#{demo_api_user_token}

  .route-section
    .route-info.indent
      %h3 Token authentication
      Simply provide your your API key in a token authorization header in the format
      %code Authorization: token [api-key]
    .route-example
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts \
             -H "Authorization: token #{demo_api_user_token}"

  .route-section
    .route-info.indent
      %h3 Query string authentication
      Simply provide your your API key as a parameter in each request in the format
      %code
        ?api_key=[api-key]
    .route-example
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts?api_key=#{demo_api_user_token}
    %a{:name => 'errors'}

  .route-section
    .route-info
      %h2 Errors
      %p easyBacklog uses conventional #{link_to 'HTTP response codes', 'http://en.wikipedia.org/wiki/List_of_HTTP_status_codes'} to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, you do not have permission to make those changes, etc.), and codes in the 5xx range indicate an error with easyBacklog's servers.
      %p Not all errors map cleanly onto HTTP response codes, however.
      %p All errors return #{link_to 'JSON', 'http://www.json.org/'} or #{link_to 'XML', 'http://en.wikipedia.org/wiki/XML'} with a type (one of card_error, invalid_request_error, or api_error) and message describing the particular problem.
      %h4 Attributes
      %dl.argument-list
        %dt status
        %dd
          For all errors the status will be set to
          %code error
        %dt message
        %dd A user-friendly message describing the error
        %dt errors (optional)
        %dd An array of error messages, if applicable.  Typically this property is set to an array when more than one validation error has occurred on an update or create request.
    .route-example
      %h2 HTTP Status Code Summary
      %code
        %ul
          %li
            %b 200
            OK - Everything worked as expected.
          %li
            %b 201
            Created - a new record has been created successfully, the response will include the new record.
          %li
            %b 204
            Success but no data - after an update or delete request, no data is returned in the response.
          %li
            %b 400
            Bad Request - Often missing a required parameter or invalid parameter.
          %li
            %b 401
            Unauthorized - Invalid API key provided.
          %li
            %b 403
            Forbidden - You do not have the necessary privileges to perform this function or the underlying data prohibits this request.
          %li
            %b 404
            Not Found - The requested item doesn't exist.
          %li
            %b 406
            Not Acceptable - The data type you requested is not supported, we only support JSON and XML.
          %li
            %b 500
            Internal server error - Something has gone wrong on our servers.
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts \
             -H "Authorization: token INVALID-TOKEN"
      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "status": "error",
              "message": "Invalid authentication details"
            }
    %a{:name => 'content-types'}

  .route-section
    .route-info
      %h2 Content types and API versioning
      %p
        The API is currently at version 1.0.  You can specify a version number as a parameter in your
        %code Accept:
        header that will ensure API compatibility for all your requests.  However, if you do not specify a version number, then your requests will be routed to the latest version of the API and thus could have unexpected results whenever we upgrade our API.  If you want to ensure API compatibility, we recommend you pass in the version number using the
        %code Accept:
        header.  Please see below for complete examples.
      %p
        The easyBacklog API will accept and respond to requests using both #{link_to 'JSON', 'http://www.json.org/'} and #{link_to 'XML', 'http://en.wikipedia.org/wiki/XML'}.  JSON is used by default, however based on the
        %code Accept
        header used, XML can be returned.  Also, if an extension suffix is added to  a URL such as
        %code /accounts.xml
        then this format will be used.
      %p
        Examples are as follows:

  .route-section.list-start
    .route-info.indent
      %h3 JSON
      %p
        We recommend you use the following header as it locks you into version 1.0 of the API and explicitly requests JSON data from the API:
        %br
        %code Accept: application/vnd.easybacklog+json; version=1.0
      %p
        The data type for each attribute in the JSON data returned is not defined explicitly, unlike in the #{link_to 'XML (example below)', '#content-type-xml'} data.
      %p
        All dates are expressed in #{link_to 'ISO 8601 format', 'http://en.wikipedia.org/wiki/ISO_8601'}.
    .route-example
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts \
             -H "Accept: application/vnd.easybacklog+json; version=1.0" \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts.json \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "created_at":"2012-05-21T21:33:51Z",
                "default_rate":null,
                "default_use_50_90":null,
                "default_velocity":null,
                "id":33,
                "locale_id":1,
                "name":"API Access Demo Account",
                "scoring_rule_id":null,
                "updated_at":"2012-05-21T21:33:51Z"
              }
            ]
    %a{:name => 'content-type-xml'}

  .route-section
    .route-info.indent
      %h3 XML
      %p
        We recommend you use the following header as it locks you into version 1.0 of the API and explicitly requests XML data from the API:
        %br
        %code Accept: application/vnd.easybacklog+xml; version=1.0
      %p
        The data type for each attribute in the XML data returned is defined in the type attribute, and all names with underscores are converted to dashes.
      %p
        All dates are expressed in #{link_to 'ISO 8601 format', 'http://en.wikipedia.org/wiki/ISO_8601'}.
    .route-example
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts \
             -H "Accept: application/vnd.easybacklog+xml; version=1.0" \
             -H "Authorization: token #{demo_api_user_token}"
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts.xml \
             -H "Authorization: token #{demo_api_user_token}"
      %code.rest.rest-response
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <accounts type="array">
              <account>
                <created-at type="datetime">2012-05-21T21:33:51Z</created-at>
                <default-rate type="integer" nil="true"></default-rate>
                <default-use-50-90 type="boolean" nil="true"></default-use-50-90>
                <default-velocity type="decimal" nil="true"></default-velocity>
                <id type="integer">33</id>
                <locale-id type="integer">1</locale-id>
                <name>API Access Demo Account</name>
                <scoring-rule-id type="integer" nil="true"></scoring-rule-id>
                <updated-at type="datetime">2012-05-21T21:33:51Z</updated-at>
              </account>
            </accounts>
    %a{:name => 'accounts'}

  .route-section
    .route-info
      %a{:name => 'account-object'}
      %h2 Accounts
      %p
        An account is the highest level container of data.  All backlogs belongs to accounts, and all users are assigned to one or more accounts.

  .route-section.list-start
    .route-info
      %h3 The Account object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this account
        %dt name
        %dd
          .data-type string
          The account name
        %dt locale_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Locale', '#locales'} applied to this account.
        %dt default_velocity
        %dd
          .data-type.nullable decimal
          Default velocity to use for new backlogs.
        %dt default_rate
        %dd
          .data-type.nullable integer
          Default rate (without currency symbol) to use for new backlogs.
        %dt default_use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% scoring rule as a default for new backlogs.  Setting this to false uses the simpler single scoring rule for stories.
        %dt scoring_rule_id
        %dd
          .data-type.foreign-key integer
          Default #{link_to 'scoring rule', '#scoring-rules'} to use for new backlogs.
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2012-05-21T21:33:51Z",
              "default_rate":null,
              "default_use_50_90":null,
              "default_velocity":null,
              "id":33,
              "locale_id":1,
              "name":"API Access Demo Account",
              "scoring_rule_id":null,
              "updated_at":"2012-05-21T21:33:51Z"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <account>
              <created-at type="datetime">2012-05-21T21:33:51Z</created-at>
              <default-rate type="integer" nil="true"></default-rate>
              <default-use-50-90 type="boolean" nil="true"></default-use-50-90>
              <default-velocity type="decimal" nil="true"></default-velocity>
              <id type="integer">33</id>
              <locale-id type="integer">1</locale-id>
              <name>API Access Demo Account</name>
              <scoring-rule-id type="integer" nil="true"></scoring-rule-id>
              <updated-at type="datetime">2012-05-21T21:33:51Z</updated-at>
            </account>

  .route-section
    .route-info
      %h3 List the Accounts

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      An array of #{link_to 'account objects', '#account-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "created_at":"2012-05-21T21:33:51Z",
                "default_rate":null,
                "default_use_50_90":null,
                "default_velocity":null,
                "id":33,
                "locale_id":1,
                "name":"API Access Demo Account",
                "scoring_rule_id":null,
                "updated_at":"2012-05-21T21:33:51Z"
              }
            ]

  .route-section
    .route-info
      %h3 Retrieve an Account

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      An #{link_to 'account object', '#account-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2012-05-21T21:33:51Z",
              "default_rate":null,
              "default_use_50_90":null,
              "default_velocity":null,
              "id":33,
              "locale_id":1,
              "name":"API Access Demo Account",
              "scoring_rule_id":null,
              "updated_at":"2012-05-21T21:33:51Z"
            }

  .route-section
    .route-info
      %h3 Update an Account

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The account name
        %dt locale_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Locale', '#locale'} applied to this account.
        %dt default_velocity
        %dd
          .data-type.nullable decimal
          Default velocity to use for new backlogs.
        %dt default_rate
        %dd
          .data-type.nullable integer
          Default rate (without currency symbol) to use for new backlogs.  Cannot be specified unless default velocity is set.
        %dt default_use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% certainty scoring rule as a default for new backlogs.
        %dt scoring_rule_id
        %dd
          .data-type.foreign-key integer
          Default #{link_to 'scoring rule', '#scoring-rule'} to use for new backlogs.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New account name" \
             -d "default_velocity=4" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'companies'}

  .route-section
    .route-info
      %a{:name => 'company-object'}
      %h2 Companies
      %p
        A company represents a business or business unit that one can group backlogs into.  A backlog can optionally be associated with a company.  If no association from backlog to a company is made, then the backlog is grouped at the account level.

  .route-section.list-start
    .route-info
      %h3 The Company object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this company
        %dt name
        %dd
          .data-type string
          The company name
        %dt default_velocity
        %dd
          .data-type.nullable decimal
          Default velocity to use for new backlogs.
        %dt default_rate
        %dd
          .data-type.nullable integer
          Default rate (without currency symbol) to use for new backlogs.
        %dt default_use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% scoring rule as a default for new backlogs.  Setting this to false uses the simpler single scoring rule for stories.
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "account_id":33,
              "created_at":"2012-05-25T17:11:20Z",
              "default_rate":800,
              "default_use_50_90":false,
              "default_velocity":"3.0",
              "id":13,
              "name":"Acme company",
              "updated_at":"2012-05-25T17:11:42Z"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <company>
              <account-id type="integer">33</account-id>
              <created-at type="datetime">2012-05-25T17:11:20Z</created-at>
              <default-rate type="integer">800</default-rate>
              <default-use-50-90 type="boolean">false</default-use-50-90>
              <default-velocity type="decimal">3.0</default-velocity>
              <id type="integer">13</id>
              <name>Acme company</name>
              <updated-at type="datetime">2012-05-25T17:11:42Z</updated-at>
            </company>

  .route-section
    .route-info
      %h3 List the Companies

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      An array of #{link_to 'company objects', '#company-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/companies'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/companies \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "account_id":33,
                "created_at":"2012-05-25T17:11:20Z",
                "default_rate":800,
                "default_use_50_90":false,
                "default_velocity":"3.0",
                "id":13,
                "name":"Acme company",
                "updated_at":"2012-05-25T17:11:42Z"
              }
            ]

  .route-section
    .route-info
      %h3 Retrieve a Company

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      A #{link_to 'company object', '#company-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/companies/{COMPANY_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/companies/#{demo_api_company_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "account_id":33,
              "created_at":"2012-05-25T17:11:20Z",
              "default_rate":800,
              "default_use_50_90":false,
              "default_velocity":"3.0",
              "id":13,
              "name":"Acme company",
              "updated_at":"2012-05-25T17:47:24Z"
            }

  .route-section
    .route-info
      %h3 Create a Company

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The company name
        %dt default_velocity
        %dd
          .data-type.nullable decimal
          Default velocity to use for new backlogs.
        %dt default_rate
        %dd
          .data-type.nullable integer
          Default rate (without currency symbol) to use for new backlogs.  Cannot be specified unless default velocity is set.
        %dt default_use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% certainty scoring rule as a default for new backlogs.

      %h4.returns Returns
      The newly created #{link_to 'company object', '#company-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/companies/{COMPANY_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/companies \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New company name" \
             -d "default_velocity=5" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "account_id":null,
              "created_at":"2012-05-25T18:02:18Z",
              "default_rate":null,
              "default_use_50_90":null,
              "default_velocity":"5.0",
              "id":14,
              "name":"New company name",
              "updated_at":"2012-05-25T18:02:18Z"
            }

  .route-section
    .route-info
      %h3 Update a Company

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The company name
        %dt default_velocity
        %dd
          .data-type.nullable decimal
          Default velocity to use for new backlogs.
        %dt default_rate
        %dd
          .data-type.nullable integer
          Default rate (without currency symbol) to use for new backlogs.  Cannot be specified unless default velocity is set.
        %dt default_use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% certainty scoring rule as a default for new backlogs.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/companies/{COMPANY_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/companies/#{demo_api_company_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New company name" \
             -d "default_velocity=5.0" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

    .route-section
    .route-info
      %h3 Delete a Company

      %h4 Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/companies/{COMPANY_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/companies/#{demo_api_company_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'backlogs'}

  .route-section
    .route-info
      %a{:name => 'backlog-object'}
      %h2 Backlogs
      %p
        An backlog object represents a user created backlog and belongs to a single #{link_to 'account', '#account'}.  A backlog contains one or more children #{link_to 'themes', '#themes'},
        #{link_to 'sprints', '#sprints'} or #{link_to 'snapshots', '#snapshots'}.

  .route-section.list-start
    .route-info
      %h3 The Backlog object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.read-only integer
          Unique identifier for this backlog
        %dt name
        %dd
          .data-type string
          The backlog name
        %dt account_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Account', '#accounts'} this backlog belongs to
        %dt company_id
        %dd
          .data-type.foreign-key-nullable integer
          #{link_to 'Company', '#company'} this backlog belongs to.  A backlog is optionally associated with a company.
        %dt velocity
        %dd
          .data-type.nullable decimal
          Average velocity per day per team member.  This is empty (null) when time estimates are not automatically created for this backlog.
        %dt rate
        %dd
          .data-type.nullable integer
          Rate per day per team member.  This is empty (null) when cost estimates are not automatically created for this backlog.
        %dt use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% scoring rule for this backlog.  When false (or null) the backlog uses the simpler single scoring rule for stories.
        %dt scoring_rule_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Scoring rule', '#scoring-rule'} used for this backlog.
        %dt archived
        %dd
          .data-type boolean
          Indicates whether the backlog has been archived (and locked).
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
        %dt *others*
        %dd
          Any other attributes that are returned are not part of the official API spec and you should not rely on their existence.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "account_id":33,
              "archived":false,
              "author_id":1,
              "company_id":null,
              "created_at":"2011-01-03T15:03:00Z",
              "id":357,
              "last_modified_user_id":1,
              "name":"Example corporate website backlog",
              "rate":800,
              "scoring_rule_id":null,
              "updated_at":"2011-02-17T15:03:00Z",
              "use_50_90":false,
              "velocity":"3.0"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <backlog>
              <account-id type="integer">33</account-id>
              <archived type="boolean">false</archived>
              <author-id type="integer">1</author-id>
              <company-id type="integer" nil="true"></company-id>
              <created-at type="datetime">2011-01-03T15:03:00Z</created-at>
              <id type="integer">357</id>
              <last-modified-user-id type="integer">1</last-modified-user-id>
              <name>Example corporate website backlog</name>
              <rate type="integer">800</rate>
              <scoring-rule-id type="integer" nil="true"></scoring-rule-id>
              <updated-at type="datetime">2011-02-17T15:03:00Z</updated-at>
              <use-50-90 type="boolean">false</use-50-90>
              <velocity type="decimal">3.0</velocity>
            </backlog>

  .route-section
    .route-info
      %h3 List the Backlogs

      %h4 Arguments
      %dl.argument-list
        %dt include_archived
        %dd
          .data-type boolean
          If set to true, all backlogs including archived backlogs will be returned.  By default, archived backlogs are filtered in the response.

      %h4.returns Returns
      An array of #{link_to 'backlog objects', '#backlog-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "account_id":33,
                "archived":false,
                "author_id":1,
                "company_id":null,
                "created_at":"2011-01-03T15:03:00Z",
                "id":357,
                "last_modified_user_id":1,
                "name":"Example corporate website backlog",
                "rate":800,
                "scoring_rule_id":null,
                "updated_at":"2011-02-17T15:03:00Z",
                "use_50_90":false,
                "velocity":"3.0"
              }
            ]
    %a{:name => 'backlog-retrieve'}

  .route-section
    .route-info
      %h3 Retrieve a Backlog

      %h4 Content types
      This route is special in that it supports the following mime types:
      %dl.argument-list
        %dt JSON
        %dd
          Use the
          %code Accept:
          header
          %code application/json
          or
          %code application/vnd.easybacklog+json; version=1.0
          or optional add the extension
          %code .json
          to the URL.
          %br
          The backlog object will be returned in JSON format.
          %h4 Arguments
          %b include associated data:
          Passing in the optional
          %code include_associated_data=true
          parameter modifies the JSON to include all #{link_to 'themes', '#themes'}, #{link_to 'sprints', '#sprints'}, #{link_to 'stories', '#stories'} and #{link_to 'acceptance criteria', '#acceptance-criteria'} related to this object.
        %dt XML
        %dd
          Use the
          %code Accept:
          header
          %code application/xml
          or
          %code application/vnd.easybacklog+xml; version=1.0
          or optional add the extension
          %code .xml
          to the URL.
          %br
          The backlog object will be returned in JSON format.
          %h4 Arguments
          %b include associated data:
          Passing in the optional
          %code include_associated_data=true
          parameter modifies the JSON to include all #{link_to 'sprints', '#sprints'}, #{link_to 'themes', '#themes'}, #{link_to 'sprints', '#sprints'}, #{link_to 'stories', '#stories'} and #{link_to 'acceptance criteria', '#acceptance-criteria'} related to this object.
        %dt Excel (XLS)
        %dd
          Use the
          %code Accept:
          header
          %code application/vnd.ms-excel
          or
          %code application/vnd.easybacklog+xls; version=1.0
          or optional add the extension
          %code .xls
          to the URL.
          %br
          The backlog object will be returned in Microsoft Excel (XML) format, including two worksheets.  The first worksheet contains the entire backlog laid out with summary data, the second worksheet simply contains a list of stories that can be autofiltered.
          %h4 Arguments
          None
        %dt PDF
        %dd
          Use the
          %code Accept:
          header
          %code application/pdf
          or
          %code application/vnd.easybacklog+pdf; version=1.0
          or optional add the extension
          %code .pdf
          to the URL.
          %br
          The story cards in printable format will be returned for the entire backlog.

          %h4 Arguments
          %b scope:
          Passing in the optional
          %code print_scope
          parameter with either
          %code sprint-{SPRINT_ID}
          or
          %code theme-{THEME_ID}
          , will filter the cards returned by that theme or sprint.
          %br
          %b page size:
          Adding the option parameter
          %code page_size=[A4|letter]
          allows you to select your page size
          %br
          %b fold side:
          As the story cards are meant to be print on double sided paper, by passing in the optional parameter
          %code fold_side=[short|long]
          you can select which side the fold is assumed on.






      %h4 Arguments
      Please see arguments specified in the content types above.

      %h4.returns Returns
      A #{link_to 'backlog object', '#backlog-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "account_id":33,
              "archived":false,
              "author_id":1,
              "company_id":null,
              "created_at":"2011-01-03T15:03:00Z",
              "id":357,
              "last_modified_user_id":1,
              "name":"Example corporate website backlog",
              "rate":800,
              "scoring_rule_id":null,
              "updated_at":"2011-02-17T15:03:00Z",
              "use_50_90":false,
              "velocity":"3.0"
            }

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}.xls \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id} \
             -d include_associated_data=true \
             -H "Authorization: token #{demo_api_user_token}" \
             -H "Accept: application/vnd.easybacklog+xml; version=1.0" \
             -X GET

  .route-section
    .route-info
      %h3 Retrieve backlog statistics

      The data that is used to generate the burn down, burn up, velocity of completed sprints and velocity charts in the Stats tab of your backlog, is available via this API.

      %h4.returns Arguments
      None

      %h4.returns Returns
      A set of objects representing the statistics relating to the current backlog.  The statistics are grouped into four objects,
      %code burn_down,
      %code burn_up,
      %code velocity_completed,
      and
      %code velocity_stats.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}/stats'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/stats \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "burn_down":{
                "trend":[
                  {
                    "starts_on":"2011-01-17",
                    "completed_on":"2011-01-17",
                    "points":90.0,
                    "iteration":0,
                    "duration":5,
                    "completed":0,
                    "team":"1.0",
                    "actual":0.0
                  }
                ],
                "actual":[
                  {
                    "starts_on":"2011-01-17",
                    "completed_on":"2011-01-17",
                    "points":90.0,
                    "iteration":0,
                    "duration":5,
                    "completed":0,
                    "team":"1.0",
                    "actual":0.0
                  }
                ],
                "projected":[
                  {
                    "starts_on":"2011-02-07",
                    "completed_on":"2011-02-11",
                    "points":27.0,
                    "iteration":4,
                    "duration":5,
                    "completed":21.0,
                    "team":"1.0",
                    "actual":4.2
                  }
                ]
              },
              "velocity_stats":{
                "expected_sprint":"15.0",
                "actual_sprint":15.75,
                "actual_day":3.1500000000000004,
                "expected_day":"3.0"
              },
              "velocity_completed":[
                {
                  "starts_on":"2011-01-17",
                  "completed_on":"2011-01-21",
                  "iteration":1,
                  "duration":5,
                  "completed":11.0,
                  "team":"1.0",
                  "actual":2.2
                }
              ],
              "burn_up":{
                "total":[
                  {
                    "starts_on":"2011-01-17",
                    "completed_on":"2011-01-21",
                    "iteration":1,
                    "duration":5,
                    "completed":11.0,
                    "total_points":71.0,
                    "team":"1.0",
                    "actual":2.2
                  }
                ],
                "actual":[
                  {
                    "starts_on":"2011-01-17",
                    "completed_on":"2011-01-21",
                    "iteration":1,
                    "duration":5,
                    "completed":11.0,
                    "total_points":0,
                    "team":"1.0",
                    "actual":2.2
                  }
                ]
              }
            }

  .route-section
    .route-info
      %h3 Create a Backlog

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The backlog name
        %dt company_id
        %dd
          .data-type.foreign-key-nullable integer
          #{link_to 'Company', '#company'} this backlog belongs to.  A backlog can also have no association with a company, so this can be empty (null).
        %dt velocity
        %dd
          .data-type.nullable decimal
          Average velocity per day per team member.  Set this to empty (null) when time estimates are not required for this backlog.
        %dt rate
        %dd
          .data-type.nullable integer
          Rate per day per team member.  Set this to empty (null) when cost estimates are not required for this backlog.  Rate cannot be specified unless velocity is set.
        %dt use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% scoring rule for this backlog.  Use false (or null) if you wish to use the simpler single scoring rule for stories.
        %dt scoring_rule_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Scoring rule', '#scoring-rule'} used for this backlog.

      %h4.returns Returns
      The newly created #{link_to 'backlog object', '#backlog-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New backlog name" \
             -d "velocity=3.5" \
             -d "rate=800" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "account_id":33,
              "archived":false,
              "author_id":1,
              "company_id":null,
              "created_at":"2012-05-23T12:16:25Z",
              "id":364,
              "last_modified_user_id":1,
              "name":"New backlog name",
              "rate":800,
              "scoring_rule_id":null,
              "updated_at":"2012-05-23T12:16:25Z",
              "use_50_90":null,
              "velocity":"3.5"
            }

  .route-section
    .route-info
      %h3 Update a Backlog

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The backlog name
        %dt company_id
        %dd
          .data-type.foreign-key-nullable integer
          #{link_to 'Company', '#company'} this backlog belongs to.  A backlog can also have no association with a company, so this can be empty (null).
        %dt velocity
        %dd
          .data-type.nullable decimal
          Average velocity per day per team member.  Set this to empty (null) when time estimates are not required for this backlog.
        %dt rate
        %dd
          .data-type.nullable integer
          Rate per day per team member.  Set this to empty (null) when cost estimates are not required for this backlog.  Rate cannot be specified unless velocity is set.
        %dt use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% scoring rule for this backlog.  Use false (or null) if you wish to use the simpler single scoring rule for stories.
        %dt scoring_rule_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Scoring rule', '#scoring-rule'} used for this backlog.
        %dt archived
        %dd
          .data-type boolean
          Set this to true to archive a backlog, and false to recover from the archives.  All archived backlogs are locked and therefore cannot be edited.
          %br
          If recovering an archive from the backlog, then all other arguments are ignored.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New backlog name" \
             -d "rate=800" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Duplicate a Backlog

      %p Duplicating a backlog copies all children themes, stories and acceptance criteria to a new backlog.  Sprints however are not copied.

      %h4.returns Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The new backlog name
        %dt company_id
        %dd
          .data-type.foreign-key-nullable integer
          #{link_to 'Company', '#company'} this backlog belongs to.  A backlog can also have no association with a company, so this can be empty (null).
        %dt velocity
        %dd
          .data-type.nullable decimal
          Average velocity per day per team member.  Set this to empty (null) when time estimates are not required for this backlog.
        %dt rate
        %dd
          .data-type.nullable integer
          Rate per day per team member.  Set this to empty (null) when cost estimates are not required for this backlog.  Rate cannot be specified unless velocity is set.
        %dt use_50_90
        %dd
          .data-type.nullable boolean
          Use the 50%/90% scoring rule for this backlog.  Use false (or null) if you wish to use the simpler single scoring rule for stories.
        %dt scoring_rule_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Scoring rule', '#scoring-rule'} used for this backlog.

      %h4.returns Returns
      The newly created #{link_to 'backlog object', '#backlog-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}/duplicate'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/duplicate \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New duplicated backlog name" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "account_id":33,
              "archived":false,
              "author_id":1,
              "company_id":null,
              "created_at":"2012-05-24T13:13:18Z",
              "id":366,
              "last_modified_user_id":1,
              "name":"New duplicated backlog name",
              "rate":800,
              "scoring_rule_id":7,
              "updated_at":"2012-05-24T13:13:18Z",
              "use_50_90":false,
              "velocity":"3.0"
            }

  .route-section
    .route-info
      %h3 Delete a Backlog

      %h4 Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'snapshots'}


  .route-section
    .route-info
      %a{:name => 'snapshot-object'}
      %h2 Snapshots
      %p
        A snapshot object represents an exact copy of a #{link_to 'backlog', '#backlogs'} in a point in time.  It belongs to a single #{link_to 'backlog', '#backlogs'}.
        A snapshot contains one or more children #{link_to 'themes', '#themes'}, which in turn contain #{link_to 'stories', '#stories'} and #{link_to 'acceptance criteria', '#acceptance-criteria'}.
        Snapshots only contain backlog data and do not contain #{link_to 'sprints', '#sprints'}.
      %p
        Snapshots are either manually created, or created automatically when a sprint starts.

  .route-section.list-start
    .route-info
      %h3 The Snapshot object

      The Snapshot object is very similar to the #{link_to 'Backlog object', '#backlog-object'}, except that it is never editable, and contains a reference to it's parent backlog or sprint.

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this snapshot.
        %dt name
        %dd
          .data-type string
          The snapshot name
        %dt parent_backlog_id or parent_sprint_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Backlog', '#backlogs'} or #{link_to 'Sprint', '#sprints'} this snapshot belongs to.  Manually created snapshots have a
          #{content_tag :code, 'parent_backlog_id'}, whereas sprint snapshots created automatically when a sprint commences have a
          #{content_tag :code, 'parent_sprint_id'}.
        %dt velocity
        %dd
          .data-type.nullable decimal
          Average velocity per day per team member.  This is empty (null) when time estimates are not automatically created for this snapshot.
        %dt rate
        %dd
          .data-type.nullable integer
          Rate per day per team member.  This is empty (null) when cost estimates are not automatically created for this snapshot.
        %dt use_50_90
        %dd
          .data-type.nullable boolean
          50%/90% scoring rule used for this snapshot.  When false (or null) the snapshot uses the simpler single scoring rule for stories.
        %dt scoring_rule_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Scoring rule', '#scoring-rule'} used for this snapshot.
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2011-01-18T19:03:49Z",
              "id":358,
              "name":"New finance section added and agreed with client",
              "rate":800,
              "scoring_rule_id":null,
              "use_50_90":false,
              "velocity":"3.0",
              "parent_backlog_id":357
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <snapshot>
              <created-at type="datetime">2011-01-18T19:03:49Z</created-at>
              <id type="integer">358</id>
              <name>New finance section added and agreed with client</name>
              <rate type="integer">800</rate>
              <scoring-rule-id type="integer" nil="true"></scoring-rule-id>
              <use-50-90 type="boolean">false</use-50-90>
              <velocity type="decimal">3.0</velocity>
              <parent-backlog-id type="integer">357</parent-backlog-id>
            </snapshot>

  .route-section
    .route-info
      %h3 List the Snapshots

      %h4 Arguments
      None

      %h4.returns Returns
      An array of #{link_to 'snapshot objects', '#snapshot-object'} grouped into
      %code manual_snapshots
      and
      #{content_tag :code, 'sprint_snapshots'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}/snapshots'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/snapshots \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "manual_snapshots":[
                {
                  "created_at":"2011-01-18T19:03:49Z",
                  "id":358,
                  "name":"New finance section added and agreed with client",
                  "rate":800,
                  "scoring_rule_id":null,
                  "use_50_90":false,
                  "velocity":"3.0",
                  "parent_backlog_id":357
                }
              ],
              "sprint_snapshots":[
                {
                  "created_at":"2011-02-07T02:00:00Z",
                  "id":363,
                  "name":"Sprint 4",
                  "rate":800,
                  "scoring_rule_id":null,
                  "use_50_90":false,
                  "velocity":"3.0",
                  "parent_sprint_id":227
                }
              ]
            }

  .route-section
    .route-info
      %h3 Retrieve a Snapshot

      %h4 Content types
      This route is special in that it supports all the additional mime types supported by the
      #{link_to 'Retrieve a Backlog', '#backlog-retrieve'}.
      Please refer to the #{link_to 'Retrieve a Backlog', '#backlog-retrieve'} section to understand the supported mime types and arguments.

      %h4.returns Arguments
      Please see arguments specified in the section #{link_to 'Retrieve a Backlog', '#backlog-retrieve'} above.

      %h4.returns Returns
      A #{link_to 'snapshot object', '#snapshot-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}/snapshots/{SNAPSHOT_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/snapshots/#{demo_api_snapshot_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2011-01-18T19:03:49Z",
              "id":358,
              "name":"New finance section added and agreed with client",
              "rate":800,
              "scoring_rule_id":null,
              "use_50_90":false,
              "velocity":"3.0",
              "parent_backlog_id":357
            }

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/snapshots/#{demo_api_snapshot_id}.xls \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/snapshots/#{demo_api_snapshot_id} \
             -d include_associated_data=true \
             -H "Authorization: token #{demo_api_user_token}" \
             -H "Accept: application/vnd.easybacklog+xml; version=1.0" \
             -X GET

  .route-section
    .route-info
      %h3 Create a Snapshot

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The new snapshot name

      %h4.returns Returns
      The newly created #{link_to 'snapshot object', '#snapshot-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}/snapshots'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/snapshots \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New snapshot name" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2012-05-24T12:44:39Z",
              "id":365,
              "name":"New snapshot name",
              "rate":800,
              "scoring_rule_id":7,
              "use_50_90":false,
              "velocity":"3.0",
              "parent_backlog_id":357
            }

  .route-section
    .route-info
      %h3 Delete a Snapshot

      Please note that you can only delete a manually created snapshot.  Sprint snapshots cannot be deleted.

      %h4.returns Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}/snapshots/{SNAPSHOT_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}accounts/#{demo_api_account_id}/backlogs/#{demo_api_backlog_id}/snapshots/#{demo_api_snapshot_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'themes'}

  .route-section
    .route-info
      %a{:name => 'theme-object'}
      %h2 Themes
      %p
        A theme object contains one or more stories in a backlog, and belongs to a single #{link_to 'backlog', '#backlogs'}.

  .route-section.list-start
    .route-info
      %h3 The Theme object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this theme
        %dt backlog_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Backlog', '#backlogs'} this theme belongs to
        %dt name
        %dd
          .data-type string
          The theme name
        %dt code
        %dd
          .data-type.auto-generated string
          A three letter unique identifier for this theme.  This code is automatically generated if not specified, but can be manually specified as well.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this theme relative to the other themes in this #{link_to 'backlog', '#backlogs'}.  Position 1 represents the first theme in the list.
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "backlog_id":366,
              "code":"HOP",
              "created_at":"2012-05-24T13:13:18Z",
              "id":1164,
              "name":"Home page",
              "position":1,
              "updated_at":"2012-05-25T17:11:20Z"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <theme>
              <backlog-id type="integer">366</backlog-id>
              <code>HOP</code>
              <created-at type="datetime">2012-05-24T13:13:18Z</created-at>
              <id type="integer">1164</id>
              <name>Home page</name>
              <position type="integer">1</position>
              <updated-at type="datetime">2012-05-25T17:11:20Z</updated-at>
            </theme>

  .route-section
    .route-info
      %h3 List the Themes

      %h4 Arguments
      %dl.argument-list
        %dt include_associated_data
        %dd
          Passing in this optional parameter will include all children #{link_to 'stories', '#stories'} and #{link_to 'acceptance criteria', '#acceptance-criteria'} for this list of themes.

      %h4.returns Returns
      An array of #{link_to 'theme objects', '#theme-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/themes'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "backlog_id":366,
                "code":"HOP",
                "created_at":"2012-05-24T13:13:18Z",
                "id":1164,
                "name":"Home page",
                "position":1,
                "updated_at":"2012-05-25T17:11:20Z"
              }
            ]

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "include_associated_data=true" \
             -X GET

    %a{:name => 'theme-retrieve'}

  .route-section
    .route-info
      %h3 Retrieve a Theme

      %h4 Arguments
      %dl.argument-list
        %dt include_associated_data
        %dd
          Passing in this optional parameter will include all children #{link_to 'stories', '#stories'} and #{link_to 'acceptance criteria', '#acceptance-criteria'} for this object.

      %h4.returns Returns
      A #{link_to 'theme object', '#theme-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/themes/{THEME_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes/#{demo_api_theme_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "backlog_id":357,
              "code":"HOP",
              "created_at":"2011-01-03T15:03:00Z",
              "id":1131,
              "name":"Home page",
              "position":1,
              "updated_at":"2012-05-23T17:42:10Z"
            }

  .route-section
    .route-info
      %h3 Create a Theme

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The theme name
        %dt code
        %dd
          .data-type.auto-generated string
          A three letter unique identifier for this theme.  This code is automatically generated if not specified, but can be manually specified as well.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this theme relative to the other themes in this #{link_to 'backlog', '#backlogs'}.  Position 1 represents the first theme in the list.

      %h4.returns Returns
      The newly created #{link_to 'theme object', '#theme-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/themes'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New theme" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "backlog_id":357,
              "code":"NET",
              "created_at":"2012-05-28T15:20:41Z",
              "id":1170,
              "name":"New theme",
              "position":6,
              "updated_at":"2012-05-28T15:20:41Z"
            }

  .route-section
    .route-info
      %h3 Update a Theme

      %h4 Arguments
      %dl.argument-list
        %dt name
        %dd
          .data-type string
          The theme name
        %dt code
        %dd
          .data-type.auto-generated string
          A three letter unique identifier for this theme.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this theme relative to the other themes in this #{link_to 'backlog', '#backlogs'}.  Position 1 represents the first theme in the list.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes/#{demo_api_theme_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "name=New theme name" \
             -d "code=NTM" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Move story from another theme

      %p You can attach a story to this theme by specifying the ID of the story that you wish to move.  The story you are moving to this theme must be assigned to another theme in the same backlog.

      %h4.returns Arguments
      %dl.argument-list
        %dt story_id
        %dd
          .data-type integer
          #{link_to 'Story', '#stories'} that you wish to move to this theme.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/themes/{THEME_ID}/grab-story'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes/#{demo_api_2nd_theme_id}/grab-story \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "story_id=#{demo_api_story_id}" \
             -X POST

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Move theme to another backlog

      %p A theme and all the stories and acceptance criteria within this theme can be moved to another backlog.  However, if the theme contains any stories that are assigned to sprints, then this request will be prohibited.

      %h4.returns Arguments
      %dl.argument-list
        %dt target_backlog_id
        %dd
          .data-type integer
          #{link_to 'Backlog', '#backlogs'} that you wish to move this theme to.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/themes/{THEME_ID}/move-to-backlog'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes/#{demo_api_2nd_theme_id}/move-to-backlog \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "target_backlog_id=#{demo_api_2nd_backlog_id}" \
             -X POST

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Delete a Theme

      %h4 Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/themes/{THEME_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/themes/#{demo_api_theme_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'sprints'}

  .route-section
    .route-info
      %a{:name => 'sprint-object'}
      %h2 Sprints
      %p
        A sprint object represents the sprint configured for a #{link_to 'backlog', '#backlog'} where one or more #{link_to 'stories', '#stories'} are assigned to the sprint.  A sprint has two states, incomplete (active and editable) or completed.  A join model is used to relate #{link_to 'stories', '#stories'} to sprints, this model is called a #{link_to 'sprint story', '#sprint-stories'} and is described below.

  .route-section.list-start
    .route-info
      %h3 The Sprint object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this sprint
        %dt backlog_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Backlog', '#backlogs'} this sprint belongs to
        %dt iteration
        %dd
          .data-type.auto-generated-read-only integer
          Represents the number of this sprint, starting at one for the first sprint.  This field is automatically assigned when the sprint is created.
        %dt start_on
        %dd
          .data-type date
          The date that this sprint starts on.  This date is important in that it dictates when a snapshot of the backlog is taken so that the current backlog can be compared against the state of the backlog when the sprint commenced.
        %dt duration_days
        %dd
          .data-type integer
          The duration in working days that this sprint lasts for.
        %dt number_team_members
        %dd
          .data-type.nullable decimal
          Represents the number of team members assigned to this sprint, and is used to calculate the expected sprint velocity based on the duration and backlog average velocity.  The number of team members can only be specified if the backlog daily velocity is specified, and must be specified unless explicit velocity for the this sprint is specified.
        %dt explicit_velocity
        %dd
          .data-type.nullable decimal
          Represents the expected velocity for this sprint.  If explicit velocity is specified, then the expected velocity for this sprint will not be calculated based on the backlog average velocity and the number of team members working on this sprint.
        %dt created_at
        %dd
          .data-type.nullable datetime
          The date that this sprint was marked as complete, or null if not complete.  A sprint can only be marked as complete if all the stories it
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
        %dt *others*
        %dd
          Any other attributes that are returned are not part of the official API spec and you should not rely on their existence.  They do serve as helpers though to provide additional information about this sprint.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "backlog_id":357,
              "completed_at":"2011-01-24T19:05:19Z",
              "created_at":"2011-01-03T15:03:00Z",
              "duration_days":5,
              "explicit_velocity":null,
              "id":224,
              "iteration":1,
              "number_team_members":"1.0",
              "start_on":"2011-01-17",
              "updated_at":"2012-05-23T17:42:10Z",
              "completed?":true,
              "deletable?":false,
              "total_allocated_points":11.0,
              "total_expected_points":"15.0",
              "total_completed_points":11.0
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <sprint>
              <backlog-id type="integer">357</backlog-id>
              <completed-at type="datetime">2011-01-24T19:05:19Z</completed-at>
              <created-at type="datetime">2011-01-03T15:03:00Z</created-at>
              <duration-days type="integer">5</duration-days>
              <explicit-velocity nil="true"></explicit-velocity>
              <id type="integer">224</id>
              <iteration type="integer">1</iteration>
              <number-team-members type="decimal">1.0</number-team-members>
              <start-on type="date">2011-01-17</start-on>
              <updated-at type="datetime">2012-05-23T17:42:10Z</updated-at>
              <total-allocated-points type="float">11.0</total-allocated-points>
              <total-expected-points type="decimal">15.0</total-expected-points>
              <total-completed-points type="float">11.0</total-completed-points>
            </sprint>

  .route-section
    .route-info
      %h3 List the Sprints

      %h4 Arguments
      %dl.argument-list
        %dt include_associated_data
        %dd
          Passing in this optional parameter will include all children #{link_to 'sprint stories', '#sprint-stories'} for this list of sprints.

      %h4.returns Returns
      An array of #{link_to 'sprint objects', '#sprint-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/sprints'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/sprints \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "backlog_id":357,
                "completed_at":"2011-01-24T19:05:19Z",
                "created_at":"2011-01-03T15:03:00Z",
                "duration_days":5,
                "explicit_velocity":null,
                "id":224,
                "iteration":1,
                "number_team_members":"1.0",
                "start_on":"2011-01-17",
                "updated_at":"2012-05-23T17:42:10Z",
                "completed?":true,
                "deletable?":false,
                "total_allocated_points":11.0,
                "total_expected_points":"15.0",
                "total_completed_points":11.0
              }
            ]

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/sprints \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "include_associated_data=true" \
             -X GET

    %a{:name => 'sprint-retrieve'}

  .route-section
    .route-info
      %h3 Retrieve a Sprint

      %h4 Arguments
      %dl.argument-list
        %dt include_associated_data
        %dd
          Passing in this optional parameter will include all children #{link_to 'sprint stories', '#sprint-stories'} for this sprint.

      %h4.returns Returns
      A #{link_to 'sprint object', '#sprint-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/sprints/{SPRINT_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/sprints/#{demo_api_sprint_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "backlog_id":357,
              "completed_at":"2011-01-24T19:05:19Z",
              "created_at":"2011-01-03T15:03:00Z",
              "duration_days":5,
              "explicit_velocity":null,
              "id":224,
              "iteration":1,
              "number_team_members":"1.0",
              "start_on":"2011-01-17",
              "updated_at":"2012-05-23T17:42:10Z",
              "completed?":true,
              "deletable?":false,
              "total_allocated_points":11.0,
              "total_expected_points":"15.0",
              "total_completed_points":11.0
            }

  .route-section
    .route-info
      %h3 Create a Sprint

      %h4 Arguments
      %dl.argument-list
        %dt start_on
        %dd
          .data-type date
          The date that this sprint starts on.  This date is important in that it dictates when a snapshot of the backlog is taken so that the current backlog can be compared against the state of the backlog when the sprint commenced.
        %dt duration_days
        %dd
          .data-type integer
          The duration in working days that this sprint lasts for.
        %dt number_team_members
        %dd
          .data-type.nullable decimal
          Represents the number of team members assigned to this sprint, and is used to calculate the expected sprint velocity based on the duration and backlog average velocity.  The number of team members can only be specified if the backlog daily velocity is specified, and must be specified unless explicit velocity for the this sprint is specified.
        %dt explicit_velocity
        %dd
          .data-type.nullable decimal
          Represents the expected velocity for this sprint.  If explicit velocity is specified, then the expected velocity for this sprint will not be calculated based on the backlog average velocity and the number of team members working on this sprint.

      %h4.returns Returns
      The newly created #{link_to 'sprint object', '#sprint-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/sprints'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/sprints \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "start_on=2012-01-02" \
             -d "explicit_velocity=30" \
             -d "duration_days=5" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "backlog_id":357,
              "completed_at":null,
              "created_at":"2012-05-29T16:08:42Z",
              "duration_days":5,
              "explicit_velocity":"30.0",
              "id":230,
              "iteration":6,
              "number_team_members":null,
              "start_on":"2012-01-02",
              "updated_at":"2012-05-29T16:08:42Z",
              "completed?":false,
              "deletable?":true,
              "total_allocated_points":0.0,
              "total_expected_points":"30.0",
              "total_completed_points":0.0
            }

  .route-section
    .route-info
      %h3 Update a Sprint

      %h4 Arguments
      %dl.argument-list
        %dt completed
        %dd
          .data-type boolean
          If this argument is passed in, all other arguments are ignored for this request.  Passing in true sets the sprint to completed, and passing in false sets a complete sprint back to its incomplete state.
        %dt start_on
        %dd
          .data-type date
          The date that this sprint starts on.  This date is important in that it dictates when a snapshot of the backlog is taken so that the current backlog can be compared against the state of the backlog when the sprint commenced.
        %dt duration_days
        %dd
          .data-type integer
          The duration in working days that this sprint lasts for.
        %dt number_team_members
        %dd
          .data-type.nullable decimal
          Represents the number of team members assigned to this sprint, and is used to calculate the expected sprint velocity based on the duration and backlog average velocity.  The number of team members can only be specified if the backlog daily velocity is specified, and must be specified unless explicit velocity for the this sprint is specified.
        %dt explicit_velocity
        %dd
          .data-type decimal
          Represents the expected velocity for this sprint.  If explicit velocity is specified, then the expected velocity for this sprint will not be calculated based on the backlog average velocity and the number of team members working on this sprint.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'accounts/{ACCOUNT_ID}/backlogs/{BACKLOG_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/sprints/#{demo_api_sprint_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "complete=true" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Delete a Sprint

      %h4 Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'backlogs/{BACKLOG_ID}/sprints/{SPRINT_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}backlogs/#{demo_api_backlog_id}/sprints/#{demo_api_sprint_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'stories'}

  .route-section
    .route-info
      %a{:name => 'story-object'}
      %h2 Stories
      %p
        A story object represents a story within a #{link_to 'theme', '#themes'}.  It contains zero or more child #{link_to 'acceptance criteria', '#acceptance-criteria'}.

  .route-section.list-start
    .route-info
      %h3 The Story object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this sprint
        %dt theme_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Theme', '#themes'} this story belongs to
        %dt unique_id
        %dd
          .data-type.auto-generated integer
          Represents a unique ID for this story within this theme.  Numbers are autogenerated starting at one.
        %dt as_a
        %dd
          .data-type.nullable string
          The "As a" field.
        %dt i_want_to
        %dd
          .data-type.nullable string
          The "I want to" field.
        %dt so_i_can
        %dd
          .data-type.nullable string
          The "So I can" field.
        %dt comments
        %dd
          .data-type.nullable string
          The "Comments" field.
        %dt score
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story if using the simple scoring rule for this backlog.
        %dt score_50
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story's 50% score if using the 50%/90% scoring rule for this backlog.
        %dt score_90
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story's 90% score if using the 50%/90% scoring rule for this backlog.
        %dt color
        %dd
          .data-type.nullable string
          An optional color can be assigned to this story using a hexadecimal value such as
          %span{:style => 'color: #FF0000'} ff0000
          for red, or
          %span{:style => 'color: #00FF00'} 00ff00
          for green.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this story relative to the other stories in this #{link_to 'theme', '#themnes'}.  Position 1 represents the first story in the list.
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "as_a":"user",
              "color":"",
              "comments":"Assumed use of JQuery Lightbox",
              "created_at":"2011-01-03T15:03:00Z",
              "i_want_to":"view a set of simple screen shots",
              "id":3158,
              "position":1,
              "so_i_can":"understand how the products work",
              "theme_id":1131,
              "unique_id":5,
              "updated_at":"2012-05-23T17:42:10Z",
              "score":"3.0"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <story>
              <as-a>user</as-a>
              <color></color>
              <comments>Assumed use of JQuery Lightbox</comments>
              <created-at type="datetime">2011-01-03T15:03:00Z</created-at>
              <i-want-to>view a set of simple screen shots</i-want-to>
              <id type="integer">3158</id>
              <position type="integer">1</position>
              <so-i-can>understand how the products work</so-i-can>
              <theme-id type="integer">1131</theme-id>
              <unique-id type="integer">5</unique-id>
              <updated-at type="datetime">2012-05-23T17:42:10Z</updated-at>
              <score type="decimal">3.0</score>
            </story>

  .route-section
    .route-info
      %h3 List the Stories

      %h4 Arguments
      %dl.argument-list
        %dt include_associated_data
        %dd
          Passing in this optional parameter will include all children #{link_to 'acceptance criteria', '#acceptance-criteria'} for this list of stories.

      %h4.returns Returns
      An array of #{link_to 'story objects', '#story-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'themes/{THEME_ID}/stories'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}themes/#{demo_api_theme_id}/stories \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "as_a":"user",
                "color":"",
                "comments":"Assumed use of JQuery Lightbox",
                "created_at":"2011-01-03T15:03:00Z",
                "i_want_to":"view a set of simple screen shots",
                "id":3158,
                "position":1,
                "so_i_can":"understand how the products work",
                "theme_id":1131,
                "unique_id":5,
                "updated_at":"2012-05-23T17:42:10Z",
                "score":"3.0"
              }
            ]

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}themes/#{demo_api_theme_id}/stories \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "include_associated_data=true" \
             -X GET

    %a{:name => 'story-retrieve'}

  .route-section
    .route-info
      %h3 Retrieve a Story

      %h4 Arguments
      %dl.argument-list
        %dt include_associated_data
        %dd
          Passing in this optional parameter will include all children #{link_to 'acceptance criteria', '#acceptance-criteria'} for this story.

      %h4.returns Returns
      A #{link_to 'story object', '#story-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'themes/{THEME_ID}/stories/{STORY_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}themes/#{demo_api_theme_id}/stories/#{demo_api_story_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "as_a":"user",
              "color":"",
              "comments":"Assumed use of JQuery Lightbox",
              "created_at":"2011-01-03T15:03:00Z",
              "i_want_to":"view a set of simple screen shots",
              "id":3158,
              "position":1,
              "so_i_can":"understand how the products work",
              "theme_id":1131,
              "unique_id":5,
              "updated_at":"2012-05-23T17:42:10Z",
              "score":"3.0"
            }

  .route-section
    .route-info
      %h3 Retrieve a Story Shortcut

      %p This method shortcut only supports GET requests and enables quite retrieval of stories based on Story_ID without having to know the Theme_ID of the parent theme.

      %h4 Arguments
      %dl.argument-list
        %dt include_associated_data
        %dd
          Passing in this optional parameter will include all children #{link_to 'acceptance criteria', '#acceptance-criteria'} for this story.

      %h4.returns Returns
      A #{link_to 'story object', '#story-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'stories/{STORY_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}stories/#{demo_api_story_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "as_a":"user",
              "color":"",
              "comments":"Assumed use of JQuery Lightbox",
              "created_at":"2011-01-03T15:03:00Z",
              "i_want_to":"view a set of simple screen shots",
              "id":3158,
              "position":1,
              "so_i_can":"understand how the products work",
              "theme_id":1131,
              "unique_id":5,
              "updated_at":"2012-05-23T17:42:10Z",
              "score":"3.0"
            }

  .route-section
    .route-info
      %h3 Create a Story

      %h4 Arguments
      %dl.argument-list
        %dt unique_id
        %dd
          .data-type.auto-generated integer
          Represents a unique ID for this story within this theme.  Numbers are autogenerated starting at one.
        %dt as_a
        %dd
          .data-type.nullable string
          The "As a" field.
        %dt i_want_to
        %dd
          .data-type.nullable string
          The "I want to" field.
        %dt so_i_can
        %dd
          .data-type.nullable string
          The "So I can" field.
        %dt comments
        %dd
          .data-type.nullable string
          The "Comments" field.
        %dt score
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story if using the simple scoring rule for this backlog.
        %dt score_50
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story's 50% score if using the 50%/90% scoring rule for this backlog.
        %dt score_90
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story's 90% score if using the 50%/90% scoring rule for this backlog.
        %dt color
        %dd
          .data-type.nullable string
          An optional color can be assigned to this story using a hexadecimal value such as
          %span{:style => 'color: #FF0000'} ff0000
          for red, or
          %span{:style => 'color: #00FF00'} 00ff00
          for green.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this story relative to the other stories in this #{link_to 'theme', '#themnes'}.  Position 1 represents the first story in the list.

      %h4.returns Returns
      The newly created #{link_to 'story object', '#story-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'themes/{THEME_ID}/stories'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}themes/#{demo_api_theme_id}/stories \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "as_a=user" \
             -d "comments=tbc" \
             -d "color=ff0000" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "as_a":"user",
              "color":"ff0000",
              "comments":"tbc",
              "created_at":"2012-05-29T16:52:09Z",
              "i_want_to":null,
              "id":3267,
              "position":5,
              "so_i_can":null,
              "theme_id":1131,
              "unique_id":6,
              "updated_at":"2012-05-29T16:52:09Z",
              "score":null
            }

  .route-section
    .route-info
      %h3 Update a Story

      %h4 Arguments
      %dl.argument-list
        %dt unique_id
        %dd
          .data-type.auto-generated integer
          Represents a unique ID for this story within this theme.  Numbers are autogenerated starting at one.
        %dt as_a
        %dd
          .data-type.nullable string
          The "As a" field.
        %dt i_want_to
        %dd
          .data-type.nullable string
          The "I want to" field.
        %dt so_i_can
        %dd
          .data-type.nullable string
          The "So I can" field.
        %dt comments
        %dd
          .data-type.nullable string
          The "Comments" field.
        %dt score
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story if using the simple scoring rule for this backlog.
        %dt score_50
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story's 50% score if using the 50%/90% scoring rule for this backlog.
        %dt score_90
        %dd
          .data-type.nullable decimal
          Number of points assigned to this story's 90% score if using the 50%/90% scoring rule for this backlog.
        %dt color
        %dd
          .data-type.nullable string
          An optional color can be assigned to this story using a hexadecimal value such as
          %span{:style => 'color: #FF0000'} ff0000
          for red, or
          %span{:style => 'color: #00FF00'} 00ff00
          for green.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this story relative to the other stories in this #{link_to 'theme', '#themnes'}.  Position 1 represents the first story in the list.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'themes/{THEME_ID}/stories/{STORY_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}themes/#{demo_api_theme_id}/stories/#{demo_api_story_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "as_a=student" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Delete a Story

      %h4 Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'themes/{THEME_ID}/stories/{STORY_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}themes/#{demo_api_theme_id}/stories/#{demo_api_story_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'acceptance-criteria'}

  .route-section
    .route-info
      %a{:name => 'acceptance-criterion-object'}
      %h2 Acceptance Criteria
      %p
        An acceptance criterion object represents the acceptance criteria assigned to a #{link_to 'story', '#stories'}.

  .route-section.list-start
    .route-info
      %h3 The Acceptance Criterion object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this acceptance criterion
        %dt story_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Story', '#stories'} this acceptance criterion belongs to.
        %dt criterion
        %dd
          .data-type.nullable string
          This criterion's value.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this story relative to the other stories in this #{link_to 'theme', '#themnes'}.  Position 1 represents the first story in the list.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "criterion":"Support for tracking code in the format ?campaign=[code]",
              "id":7658,
              "position":1,
              "story_id":3159
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <story>
            <acceptance-criterion>
              <criterion>Support for tracking code in the format ?campaign=[code]</criterion>
              <id type="integer">7658</id>
              <position type="integer">1</position>
              <story-id type="integer">3159</story-id>
            </acceptance-criterion>

  .route-section
    .route-info
      %h3 List the Acceptance Criteria

      %h4 Arguments
      None

      %h4.returns Returns
      An array of #{link_to 'acceptance criterion objects', '#acceptance-criterion-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'stories/{STORY_ID}/acceptance-criteria'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}stories/#{demo_api_story_id}/acceptance-criteria \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "criterion":"Support for tracking code in the format ?campaign=[code]",
                "id":7658,
                "position":1,
                "story_id":3159
              }
            ]

      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}stories/#{demo_api_story_id}/acceptance-criteria \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "include_associated_data=true" \
             -X GET

    %a{:name => 'sprint-retrieve'}

  .route-section
    .route-info
      %h3 Retrieve an Acceptance Criterion

      %h4 Arguments
      None

      %h4.returns Returns
      An #{link_to 'acceptance criterion object', '#acceptance-criterion-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'stories/{STORY_ID}/acceptance-criteria/{ACCEPTANCE_CRITERIA_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}stories/#{demo_api_story_id}/acceptance-criteria/#{demo_api_acceptance_criterion_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "criterion":"Support for tracking code in the format ?campaign=[code]",
              "id":7658,
              "position":1,
              "story_id":3159
            }

  .route-section
    .route-info
      %h3 Create an Acceptance Criterion

      %h4 Arguments
      %dl.argument-list
        %dt criterion
        %dd
          .data-type.nullable string
          This criterion's value.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this story relative to the other stories in this #{link_to 'theme', '#themnes'}.  Position 1 represents the first story in the list.

      %h4.returns Returns
      The newly created #{link_to 'acceptance criterion object', '#acceptance-criterion-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'stories/{STORY_ID}/acceptance-criteria'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}stories/#{demo_api_story_id}/acceptance-criteria \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "criterion=Must validate user details" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "criterion":"Must validation user details",
              "id":7941,
              "position":1,
              "story_id":3267
            }

  .route-section
    .route-info
      %h3 Update an Acceptance Criterion

      %h4 Arguments
      %dl.argument-list
        %dt criterion
        %dd
          .data-type.nullable string
          This criterion's value.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of this story relative to the other stories in this #{link_to 'theme', '#themnes'}.  Position 1 represents the first story in the list.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'stories/{STORY_ID}/acceptance-criteria/{ACCEPTANCE_CRITERIA_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}stories/#{demo_api_story_id}/acceptance-criteria/#{demo_api_acceptance_criterion_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "criterion=Must validate user details using Javascript" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Delete an Acceptance Criterion

      %h4 Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'stories/{STORY_ID}/acceptance-criteria/{ACCEPTANCE_CRITERIA_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}stories/#{demo_api_story_id}/acceptance-criteria/#{demo_api_acceptance_criterion_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content
    %a{:name => 'sprint-stories'}

  .route-section
    .route-info
      %a{:name => 'sprint-story-object'}
      %h2 Sprint Stories
      %p
        A sprint story object represents a join between a #{link_to 'sprint object', '#sprints'} and a #{link_to 'story object', '#stories'}.  When a #{link_to 'story', '#stories'} is assigned to a #{link_to 'sprint', '#sprints'}, a sprint story object is created linking the two objects.

  .route-section.list-start
    .route-info
      %h3 The Sprint Story object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this sprint story.
        %dt sprint_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Sprint', '#sprint'} this sprint story belongs to.
        %dt story_id
        %dd
          .data-type.foreign-key-read-only integer
          #{link_to 'Story', '#story'} that is being assigned to the #{link_to 'sprint', '#sprint'}.
        %dt sprint_story_status_id
        %dd
          .data-type.foreign-key integer
          The #{link_to 'sprint story status', '#sprint-stories-statuses'} represents the state of the #{link_to 'story', '#story'} in the assigned #{link_to 'sprint', '#sprint'}, such as
          %code To Do or
          %code Accepted.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of the story relative to the other stories for this #{link_to 'sprint', '#sprint'}.  Position 1 represents the first story in the list.
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2011-01-03T15:03:00Z",
              "id":525,
              "position":1,
              "sprint_id":224,
              "sprint_story_status_id":4,
              "story_id":3159,
              "updated_at":"2012-05-23T17:42:10Z"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <sprint-story>
              <created-at type="datetime">2011-01-03T15:03:00Z</created-at>
              <id type="integer">525</id>
              <position type="integer">1</position>
              <sprint-id type="integer">224</sprint-id>
              <sprint-story-status-id type="integer">4</sprint-story-status-id>
              <story-id type="integer">3159</story-id>
              <updated-at type="datetime">2012-05-23T17:42:10Z</updated-at>
            </sprint-story>

  .route-section
    .route-info
      %h3 List the Sprint Stories

      %h4 Arguments
      None

      %h4.returns Returns
      An array of #{link_to 'sprint story objects', '#sprint-stories'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'sprints/{SPRINT_ID}/sprint-stories'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}sprints/#{demo_api_sprint_id}/sprint-stories \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "created_at":"2011-01-03T15:03:00Z",
                "id":525,
                "position":1,
                "sprint_id":224,
                "sprint_story_status_id":4,
                "story_id":3159,
                "updated_at":"2012-05-23T17:42:10Z"
              }
            ]

  .route-section
    .route-info
      %h3 Retrieve a Sprint Story

      %h4 Arguments
      None

      %h4.returns Returns
      A #{link_to 'sprint story object', '#sprint-story-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'sprints/{SPRINT_ID}/sprint-stories/{SPRINT_STORY_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}sprints/#{demo_api_sprint_id}/sprint-stories/#{demo_api_sprint_story_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2011-01-03T15:03:00Z",
              "id":525,
              "position":1,
              "sprint_id":224,
              "sprint_story_status_id":4,
              "story_id":3159,
              "updated_at":"2012-05-23T17:42:10Z"
            }

  .route-section
    .route-info
      %h3 Create a Sprint Story (assign a story to a sprint)

      %h4 Arguments
      %dl.argument-list
        %dt story_id
        %dd
          .data-type.foreign-key integer
          #{link_to 'Story', '#story'} that is being assigned to the #{link_to 'sprint', '#sprint'}.
        %dt sprint_story_status_id
        %dd
          .data-type.foreign-key integer
          The #{link_to 'sprint story status', '#sprint-stories-statuses'} represents the state of the #{link_to 'story', '#story'} in the assigned #{link_to 'sprint', '#sprint'}, such as
          %code To Do or
          %code Accepted.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of the story relative to the other stories for this #{link_to 'sprint', '#sprint'}.  Position 1 represents the first story in the list.

      %h4.returns Returns
      The newly created #{link_to 'sprint story object', '#sprint-story-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'sprints/{SPRINT_ID}/sprint-stories'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}sprints/#{demo_api_sprint_id}/sprint-stories \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "story_id=#{demo_api_story_id}" \
             -d "sprint_story_status_id=#{demo_api_sprint_story_status_id}" \
             -X POST

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "created_at":"2012-05-29T17:43:23Z",
              "id":538,
              "position":3,
              "sprint_id":228,
              "sprint_story_status_id":1,
              "story_id":3267,
              "updated_at":"2012-05-29T17:43:23Z"
            }

  .route-section
    .route-info
      %h3 Update a Sprint Story

      %h4 Arguments
      %dl.argument-list
        %dt move_to_sprint_id
        %dd
          .data-type.foreign integer
          Specify this value if you want to move this sprint story to another #{link_to 'Sprint', '#sprints'}, meaning that the story and this object are reassigned.
        %dt sprint_story_status_id
        %dd
          .data-type.foreign-key integer
          The #{link_to 'sprint story status', '#sprint-stories-statuses'} represents the state of the #{link_to 'story', '#story'} in the assigned #{link_to 'sprint', '#sprint'}, such as
          %code To Do or
          %code Accepted.
        %dt position
        %dd
          .data-type.auto-generated integer
          Position of the story relative to the other stories for this #{link_to 'sprint', '#sprint'}.  Position 1 represents the first story in the list.

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'sprints/{SPRINT_ID}/sprint-stories/{SPRINT_STORY_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}sprints/#{demo_api_sprint_id}/sprint-stories/#{demo_api_sprint_story_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -d "sprint_story_status_id=#{demo_api_sprint_story_status_id}" \
             -X PUT

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

  .route-section
    .route-info
      %h3 Delete a Sprint Story

      %h4 Arguments
      None

      %h4.returns Returns
      Nothing, will respond with a
      %code 204
      HTTP response header if successful.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'sprints/{SPRINT_ID}/sprint-stories/{SPRINT_STORY_ID}'
      %code.rest.rest-request.rest-locked
        .prompt
        :preserve
          curl #{api_end_point}sprints/#{demo_api_sprint_id}/sprint-stories/#{demo_api_sprint_story_id} \
             -H "Authorization: token #{demo_api_user_token}" \
             -X DELETE

      %code.rest.rest-response-header
        HTTP/1.1 204 No Content

    %a{:name => 'locales'}

  .route-section
    .route-info
      %a{:name => 'locale-object'}
      %h2 Locales
      %p
        A locale represents a an environment based on language and cultural conventions.  An example locale is American English ($).  The locale used in the #{link_to 'account', '#accounts'} effects how dates, currencies and sometimes messages are displayed.

  .route-section.list-start
    .route-info
      %h3 The Locale object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this locale.
        %dt name
        %dd
          .data-type string
          The locale name.
        %dt code
        %dd
          .data-type string
          The locale code.
        %dt position
        %dd
          .data-type integer
          The position of this locale with one indicating the first in the list.
        %dt created_at
        %dd
          .data-type.read-only datetime
          Date that this object was created.
        %dt updated_at
        %dd
          .data-type.read-only datetime
          Date that this object was last updated.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "code":"en-US",
              "created_at":"2011-02-18T02:53:12Z",
              "id":1,
              "name":"American English ($)",
              "position":10,
              "updated_at":"2012-01-11T22:57:26Z"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <locale>
              <code>en-US</code>
              <created-at type="datetime">2011-02-18T02:53:12Z</created-at>
              <id type="integer">1</id>
              <name>American English ($)</name>
              <position type="integer">10</position>
              <updated-at type="datetime">2012-01-11T22:57:26Z</updated-at>
            </locale>

  .route-section
    .route-info
      %h3 List the Locales

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      An array of #{link_to 'locale objects', '#locale-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'locales'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}locales \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "code":"en-US",
                "created_at":"2011-02-18T02:53:12Z",
                "id":1,
                "name":"American English ($)",
                "position":10,
                "updated_at":"2012-01-11T22:57:26Z"
              }
            ]

  .route-section
    .route-info
      %h3 Retrieve a Locale

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      A #{link_to 'locale object', '#locale-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'locale/{LOCALE_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}locales/#{demo_api_locale_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "code":"en-US",
              "created_at":"2011-02-18T02:53:12Z",
              "id":1,
              "name":"American English ($)",
              "position":10,
              "updated_at":"2012-01-11T22:57:26Z"
            }
    %a{:name => 'scoring-rules'}

  .route-section
    .route-info
      %a{:name => 'scoring-rules-object'}
      %h2 Scoring Rules
      %p
        A scoring rule represents the types of scores that can be assigned to a story.  For example, the Strict Fibanacci rule dictates that only 0, 1, 2, 3, 5, 8, 13, 21, and 34 can be used.

  .route-section.list-start
    .route-info
      %h3 The Scoring Rule object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this scoring rule.
        %dt title
        %dd
          .data-type string
          The scoring rule title.
        %dt code
        %dd
          .data-type string
          The scoring rule short code.
        %dt description
        %dd
          .data-type string
          The description of this scoring rule.
        %dt position
        %dd
          .data-type integer
          The position of this scoring rule with one indicating the first in the list.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "code":"M",
              "description":"0, 0.5, 1, 2, 3, 5, 8, 13, 20, 21, 40, 60, 100",
              "id":7,
              "position":1,
              "title":"Modified Fibonacci"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <scoring-rule>
              <code>M</code>
              <description>0, 0.5, 1, 2, 3, 5, 8, 13, 20, 21, 40, 60, 100</description>
              <id type="integer">7</id>
              <position type="integer">1</position>
              <title>Modified Fibonacci</title>
            </scoring-rule>

  .route-section
    .route-info
      %h3 List the Scoring Rules

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      An array of #{link_to 'scoring rule objects', '#scoring-rule-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'scoring-rules'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}scoring-rules \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "code":"M",
                "description":"0, 0.5, 1, 2, 3, 5, 8, 13, 20, 21, 40, 60, 100",
                "id":7,
                "position":1,
                "title":"Modified Fibonacci"
              }
            ]

  .route-section
    .route-info
      %h3 Retrieve a Scoring Rule

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      A #{link_to 'scoring rule object', '#scoring-rule-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'scoring-rules/{SCORING_RULE_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}scoring-rules/#{demo_api_scoring_rule_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "code":"M",
              "description":"0, 0.5, 1, 2, 3, 5, 8, 13, 20, 21, 40, 60, 100",
              "id":7,
              "position":1,
              "title":"Modified Fibonacci"
            }
    %a{:name => 'sprint-story-statuses'}

  .route-section
    .route-info
      %a{:name => 'sprint-story-status-object'}
      %h2 Sprint Story Statuses
      %p
        A sprint story status represents the state of a story in regards to its completeness in a sprint.  For example, a sprint story status may be
        %code To Do
        or
        %code Accepted.

  .route-section.list-start
    .route-info
      %h3 The Sprint Story Status object

      %h4 Attributes
      %dl.argument-list
        %dt id
        %dd
          .data-type.auto-generated-read-only integer
          Unique identifier for this sprint story status rule.
        %dt status
        %dd
          .data-type string
          The status description.
        %dt code
        %dd
          .data-type string
          The sprint story status short code.
        %dt position
        %dd
          .data-type integer
          The position of this sprint story status with one indicating the first in the list.
    .route-example
      %code.rest.rest-response-json
        %pre{:class => 'brush: js'}
          :preserve
            {
              "code":"T",
              "id":1,
              "position":1,
              "status":"To do"
            }

      %code.rest.rest-response-xml
        %pre{:class => 'brush: xml'}
          :preserve
            <?xml version="1.0" encoding="UTF-8"?>
            <sprint-story-status>
              <code>T</code>
              <id type="integer">1</id>
              <position type="integer">1</position>
              <status>To do</status>
            </sprint-story-status>

  .route-section
    .route-info
      %h3 List the Sprint Story Statuses

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      An array of #{link_to 'sprint story status objects', '#sprint-story-status-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'sprint-story-statuses'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}sprint-story-statuses \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            [
              {
                "code":"T",
                "id":1,
                "position":1,
                "status":"To do"
              }
            ]

  .route-section
    .route-info
      %h3 Retrieve a Sprint Story Status

      %h4 Arguments
      This request requires no arguments.

      %h4.returns Returns
      A #{link_to 'sprint story status object', '#sprint-story-status-object'}.

    .route-example
      %code.rest.rest-definition= definition_url_wrappable 'sprint-story-statuses/{SPRINT_STORY_STATUS_ID}'
      %code.rest.rest-request
        .prompt
        :preserve
          curl #{api_end_point}sprint-story-statuses/#{demo_api_sprint_story_status_id} \
             -H "Authorization: token #{demo_api_user_token}"

      %code.rest.rest-response
        %pre{:class => 'brush: js'}
          :preserve
            {
              "code":"T",
              "id":1,
              "position":1,
              "status":"To do"
            }

        %p